/**
 * @file cdbus.h
 * @brief CDBUS协议头文件
 * @details CDBUS通信协议的头文件定义，包含协议常量、数据结构和API接口
 *          CDBUS是一个基于主从架构的多节点通信协议，支持单播、广播和组播
 * 
 * @author 修改团队：mastwet@Undefine Innovation
 * @date 2024
 * @copyright MIT License
 */

#ifndef CDBUS_H
#define CDBUS_H

#include <stdint.h>
#include <stdbool.h>

/**
 * @defgroup cdbus_constants CDBUS协议常量定义
 * @brief CDBUS协议使用的常量定义
 * @{
 */

/**
 * @brief 最大用户数据长度
 * @details CDBUS帧中用户数据的最大长度，不包括协议头
 */
#define CDBUS_MAX_DATA_SIZE 253

/**
 * @brief 最大帧长度
 * @details 完整CDBUS帧的最大长度，包括协议头和CRC
 */
#define CDBUS_MAX_FRAME_SIZE 256

/**
 * @brief 广播地址
 * @details CDBUS协议中的广播地址，所有节点都会接收
 */
#define CDBUS_BROADCAST_ADDR 255

/**
 * @brief 协议头长度
 * @details CDBUS协议头的固定长度（源地址+目标地址+数据长度）
 */
#define CDBUS_HEADER_SIZE 3

/**
 * @brief CRC校验码长度
 * @details CRC16校验码的长度（2字节）
 */
#define CDBUS_CRC_SIZE 2

/**
 * @brief 数据偏移量
 * @details 用户数据在帧中的起始偏移位置
 */
#define CDBUS_DATA_OFFSET 3

/**
 * @brief 源地址偏移量
 * @details 源地址在帧中的偏移位置
 */
#define CDBUS_SRC_OFFSET 0

/**
 * @brief 目标地址偏移量
 * @details 目标地址在帧中的偏移位置
 */
#define CDBUS_DST_OFFSET 1

/**
 * @brief 数据长度偏移量
 * @details 数据长度字段在帧中的偏移位置
 */
#define CDBUS_LEN_OFFSET 2

/**
 * @brief 最小帧长度
 * @details 完整CDBUS帧的最小长度（协议头+CRC）
 */
#define CDBUS_MIN_FRAME_SIZE (CDBUS_HEADER_SIZE + CDBUS_CRC_SIZE)

/**
 * @brief 组播地址基址
 * @details 组播地址范围：0xF0-0xFE
 */
#define CDBUS_MULTICAST_BASE 0xF0

/** @} */ // CDBUS协议常量定义组结束

/**
 * @defgroup cdbus_structures CDBUS数据结构定义
 * @brief CDBUS协议使用的核心数据结构
 * @{
 */

/**
 * @brief CDBUS帧结构体
 * @details 定义CDBUS协议的数据帧格式
 */
typedef struct {
    uint8_t src_addr;                   /**< 源节点地址（0-254） */
    uint8_t dst_addr;                   /**< 目标节点地址（0-255，255为广播） */
    uint8_t data_len;                   /**< 用户数据长度（0-253字节） */
    uint8_t data[CDBUS_MAX_DATA_SIZE];  /**< 用户数据缓冲区 */
    uint16_t crc;                       /**< CRC16校验码 */
} cdbus_frame_t;

/**
 * @brief CDBUS状态枚举
 * @details 定义CDBUS协议接收状态机的状态
 */
typedef enum {
    CDBUS_STATE_IDLE = 0,       /**< 空闲状态，等待帧起始 */
    CDBUS_STATE_RECEIVING,      /**< 接收状态，正在接收帧数据 */
    CDBUS_STATE_COMPLETE,       /**< 完成状态，已接收到完整有效帧 */
    CDBUS_STATE_ERROR           /**< 错误状态，接收过程中发生错误 */
} cdbus_state_t;

/**
 * @brief CDBUS协议实例结构体
 * @details 包含CDBUS协议栈的所有状态信息和缓冲区
 */
typedef struct {
    uint8_t address;                    /**< 本节点地址（0-254） */
    uint8_t filter;                     /**< 地址过滤器 */
    cdbus_state_t state;                /**< 当前接收状态 */
    uint8_t rx_buffer[CDBUS_MAX_FRAME_SIZE]; /**< 接收缓冲区 */
    uint8_t rx_index;                   /**< 接收缓冲区索引 */
    uint8_t expected_len;               /**< 期望接收的帧长度 */
    uint16_t calculated_crc;            /**< 计算的CRC值（保留） */
    cdbus_frame_t frame;                /**< 解析后的帧数据 */
} cdbus_t;

/** @} */ // CDBUS数据结构定义组结束

/**
 * @defgroup cdbus_api CDBUS API接口
 * @brief CDBUS协议栈提供的核心API函数
 * @{
 */

/**
 * @brief 初始化CDBUS协议实例
 * @param cdbus CDBUS实例指针
 * @param address 本节点地址（0-254）
 */
void cdbus_init(cdbus_t *cdbus, uint8_t address);

/**
 * @brief 设置地址过滤器
 * @param cdbus CDBUS实例指针
 * @param filter 过滤器地址
 */
void cdbus_set_filter(cdbus_t *cdbus, uint8_t filter);

/**
 * @brief 重置CDBUS接收状态机
 * @param cdbus CDBUS实例指针
 */
void cdbus_reset(cdbus_t *cdbus);

/**
 * @brief 处理接收到的单个字节数据
 * @param cdbus CDBUS实例指针
 * @param byte 接收到的字节数据
 * @return 处理结果状态码
 */
int cdbus_process_byte(cdbus_t *cdbus, uint8_t byte);

/**
 * @brief 获取接收到的完整帧数据
 * @param cdbus CDBUS实例指针
 * @param frame 用于存储帧数据的缓冲区
 * @return 获取结果状态码
 */
int cdbus_get_frame(cdbus_t *cdbus, cdbus_frame_t *frame);

/**
 * @brief 创建CDBUS协议帧
 * @param src 源节点地址
 * @param dst 目标节点地址
 * @param data 用户数据缓冲区指针
 * @param len 用户数据长度
 * @param buffer 用于存储完整帧的缓冲区
 * @return 完整帧长度（字节数）
 */
int cdbus_create_frame(uint8_t src, uint8_t dst, uint8_t *data, uint8_t len, uint8_t *buffer);

/**
 * @brief 计算数据的CRC16校验值
 * @param data 数据缓冲区指针
 * @param len 数据长度
 * @return CRC16校验值
 */
uint16_t cdbus_calculate_crc(uint8_t *data, uint8_t len);

/** @} */ // CDBUS API接口组结束

#endif // CDBUS_H